Autogenerated HTML docs for v1.8.1-rc2-38-gb10c4 
diff --git a/howto/new-command.html b/howto/new-command.html new file mode 100644 index 0000000..138a5d9 --- /dev/null +++ b/howto/new-command.html 
@@ -0,0 +1,864 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"  + "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">  +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">  +<head>  +<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />  +<meta name="generator" content="AsciiDoc 8.6.8" />  +<title>How to integrate new subcommands</title>  +<style type="text/css">  +/* Shared CSS for AsciiDoc xhtml11 and html5 backends */  +  +/* Default font. */  +body {  + font-family: Georgia,serif;  +}  +  +/* Title font. */  +h1, h2, h3, h4, h5, h6,  +div.title, caption.title,  +thead, p.table.header,  +#toctitle,  +#author, #revnumber, #revdate, #revremark,  +#footer {  + font-family: Arial,Helvetica,sans-serif;  +}  +  +body {  + margin: 1em 5% 1em 5%;  +}  +  +a {  + color: blue;  + text-decoration: underline;  +}  +a:visited {  + color: fuchsia;  +}  +  +em {  + font-style: italic;  + color: navy;  +}  +  +strong {  + font-weight: bold;  + color: #083194;  +}  +  +h1, h2, h3, h4, h5, h6 {  + color: #527bbd;  + margin-top: 1.2em;  + margin-bottom: 0.5em;  + line-height: 1.3;  +}  +  +h1, h2, h3 {  + border-bottom: 2px solid silver;  +}  +h2 {  + padding-top: 0.5em;  +}  +h3 {  + float: left;  +}  +h3 + * {  + clear: left;  +}  +h5 {  + font-size: 1.0em;  +}  +  +div.sectionbody {  + margin-left: 0;  +}  +  +hr {  + border: 1px solid silver;  +}  +  +p {  + margin-top: 0.5em;  + margin-bottom: 0.5em;  +}  +  +ul, ol, li > p {  + margin-top: 0;  +}  +ul > li { color: #aaa; }  +ul > li > * { color: black; }  +  +.monospaced, code, pre {  + font-family: "Courier New", Courier, monospace;  + font-size: inherit;  + color: navy;  + padding: 0;  + margin: 0;  +}  +  +  +#author {  + color: #527bbd;  + font-weight: bold;  + font-size: 1.1em;  +}  +#email {  +}  +#revnumber, #revdate, #revremark {  +}  +  +#footer {  + font-size: small;  + border-top: 2px solid silver;  + padding-top: 0.5em;  + margin-top: 4.0em;  +}  +#footer-text {  + float: left;  + padding-bottom: 0.5em;  +}  +#footer-badges {  + float: right;  + padding-bottom: 0.5em;  +}  +  +#preamble {  + margin-top: 1.5em;  + margin-bottom: 1.5em;  +}  +div.imageblock, div.exampleblock, div.verseblock,  +div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,  +div.admonitionblock {  + margin-top: 1.0em;  + margin-bottom: 1.5em;  +}  +div.admonitionblock {  + margin-top: 2.0em;  + margin-bottom: 2.0em;  + margin-right: 10%;  + color: #606060;  +}  +  +div.content { /* Block element content. */  + padding: 0;  +}  +  +/* Block element titles. */  +div.title, caption.title {  + color: #527bbd;  + font-weight: bold;  + text-align: left;  + margin-top: 1.0em;  + margin-bottom: 0.5em;  +}  +div.title + * {  + margin-top: 0;  +}  +  +td div.title:first-child {  + margin-top: 0.0em;  +}  +div.content div.title:first-child {  + margin-top: 0.0em;  +}  +div.content + div.title {  + margin-top: 0.0em;  +}  +  +div.sidebarblock > div.content {  + background: #ffffee;  + border: 1px solid #dddddd;  + border-left: 4px solid #f0f0f0;  + padding: 0.5em;  +}  +  +div.listingblock > div.content {  + border: 1px solid #dddddd;  + border-left: 5px solid #f0f0f0;  + background: #f8f8f8;  + padding: 0.5em;  +}  +  +div.quoteblock, div.verseblock {  + padding-left: 1.0em;  + margin-left: 1.0em;  + margin-right: 10%;  + border-left: 5px solid #f0f0f0;  + color: #888;  +}  +  +div.quoteblock > div.attribution {  + padding-top: 0.5em;  + text-align: right;  +}  +  +div.verseblock > pre.content {  + font-family: inherit;  + font-size: inherit;  +}  +div.verseblock > div.attribution {  + padding-top: 0.75em;  + text-align: left;  +}  +/* DEPRECATED: Pre version 8.2.7 verse style literal block. */  +div.verseblock + div.attribution {  + text-align: left;  +}  +  +div.admonitionblock .icon {  + vertical-align: top;  + font-size: 1.1em;  + font-weight: bold;  + text-decoration: underline;  + color: #527bbd;  + padding-right: 0.5em;  +}  +div.admonitionblock td.content {  + padding-left: 0.5em;  + border-left: 3px solid #dddddd;  +}  +  +div.exampleblock > div.content {  + border-left: 3px solid #dddddd;  + padding-left: 0.5em;  +}  +  +div.imageblock div.content { padding-left: 0; }  +span.image img { border-style: none; }  +a.image:visited { color: white; }  +  +dl {  + margin-top: 0.8em;  + margin-bottom: 0.8em;  +}  +dt {  + margin-top: 0.5em;  + margin-bottom: 0;  + font-style: normal;  + color: navy;  +}  +dd > *:first-child {  + margin-top: 0.1em;  +}  +  +ul, ol {  + list-style-position: outside;  +}  +ol.arabic {  + list-style-type: decimal;  +}  +ol.loweralpha {  + list-style-type: lower-alpha;  +}  +ol.upperalpha {  + list-style-type: upper-alpha;  +}  +ol.lowerroman {  + list-style-type: lower-roman;  +}  +ol.upperroman {  + list-style-type: upper-roman;  +}  +  +div.compact ul, div.compact ol,  +div.compact p, div.compact p,  +div.compact div, div.compact div {  + margin-top: 0.1em;  + margin-bottom: 0.1em;  +}  +  +tfoot {  + font-weight: bold;  +}  +td > div.verse {  + white-space: pre;  +}  +  +div.hdlist {  + margin-top: 0.8em;  + margin-bottom: 0.8em;  +}  +div.hdlist tr {  + padding-bottom: 15px;  +}  +dt.hdlist1.strong, td.hdlist1.strong {  + font-weight: bold;  +}  +td.hdlist1 {  + vertical-align: top;  + font-style: normal;  + padding-right: 0.8em;  + color: navy;  +}  +td.hdlist2 {  + vertical-align: top;  +}  +div.hdlist.compact tr {  + margin: 0;  + padding-bottom: 0;  +}  +  +.comment {  + background: yellow;  +}  +  +.footnote, .footnoteref {  + font-size: 0.8em;  +}  +  +span.footnote, span.footnoteref {  + vertical-align: super;  +}  +  +#footnotes {  + margin: 20px 0 20px 0;  + padding: 7px 0 0 0;  +}  +  +#footnotes div.footnote {  + margin: 0 0 5px 0;  +}  +  +#footnotes hr {  + border: none;  + border-top: 1px solid silver;  + height: 1px;  + text-align: left;  + margin-left: 0;  + width: 20%;  + min-width: 100px;  +}  +  +div.colist td {  + padding-right: 0.5em;  + padding-bottom: 0.3em;  + vertical-align: top;  +}  +div.colist td img {  + margin-top: 0.3em;  +}  +  +@media print {  + #footer-badges { display: none; }  +}  +  +#toc {  + margin-bottom: 2.5em;  +}  +  +#toctitle {  + color: #527bbd;  + font-size: 1.1em;  + font-weight: bold;  + margin-top: 1.0em;  + margin-bottom: 0.1em;  +}  +  +div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {  + margin-top: 0;  + margin-bottom: 0;  +}  +div.toclevel2 {  + margin-left: 2em;  + font-size: 0.9em;  +}  +div.toclevel3 {  + margin-left: 4em;  + font-size: 0.9em;  +}  +div.toclevel4 {  + margin-left: 6em;  + font-size: 0.9em;  +}  +  +span.aqua { color: aqua; }  +span.black { color: black; }  +span.blue { color: blue; }  +span.fuchsia { color: fuchsia; }  +span.gray { color: gray; }  +span.green { color: green; }  +span.lime { color: lime; }  +span.maroon { color: maroon; }  +span.navy { color: navy; }  +span.olive { color: olive; }  +span.purple { color: purple; }  +span.red { color: red; }  +span.silver { color: silver; }  +span.teal { color: teal; }  +span.white { color: white; }  +span.yellow { color: yellow; }  +  +span.aqua-background { background: aqua; }  +span.black-background { background: black; }  +span.blue-background { background: blue; }  +span.fuchsia-background { background: fuchsia; }  +span.gray-background { background: gray; }  +span.green-background { background: green; }  +span.lime-background { background: lime; }  +span.maroon-background { background: maroon; }  +span.navy-background { background: navy; }  +span.olive-background { background: olive; }  +span.purple-background { background: purple; }  +span.red-background { background: red; }  +span.silver-background { background: silver; }  +span.teal-background { background: teal; }  +span.white-background { background: white; }  +span.yellow-background { background: yellow; }  +  +span.big { font-size: 2em; }  +span.small { font-size: 0.6em; }  +  +span.underline { text-decoration: underline; }  +span.overline { text-decoration: overline; }  +span.line-through { text-decoration: line-through; }  +  +div.unbreakable { page-break-inside: avoid; }  +  +  +/*  + * xhtml11 specific  + *  + * */  +  +div.tableblock {  + margin-top: 1.0em;  + margin-bottom: 1.5em;  +}  +div.tableblock > table {  + border: 3px solid #527bbd;  +}  +thead, p.table.header {  + font-weight: bold;  + color: #527bbd;  +}  +p.table {  + margin-top: 0;  +}  +/* Because the table frame attribute is overriden by CSS in most browsers. */  +div.tableblock > table[frame="void"] {  + border-style: none;  +}  +div.tableblock > table[frame="hsides"] {  + border-left-style: none;  + border-right-style: none;  +}  +div.tableblock > table[frame="vsides"] {  + border-top-style: none;  + border-bottom-style: none;  +}  +  +  +/*  + * html5 specific  + *  + * */  +  +table.tableblock {  + margin-top: 1.0em;  + margin-bottom: 1.5em;  +}  +thead, p.tableblock.header {  + font-weight: bold;  + color: #527bbd;  +}  +p.tableblock {  + margin-top: 0;  +}  +table.tableblock {  + border-width: 3px;  + border-spacing: 0px;  + border-style: solid;  + border-color: #527bbd;  + border-collapse: collapse;  +}  +th.tableblock, td.tableblock {  + border-width: 1px;  + padding: 4px;  + border-style: solid;  + border-color: #527bbd;  +}  +  +table.tableblock.frame-topbot {  + border-left-style: hidden;  + border-right-style: hidden;  +}  +table.tableblock.frame-sides {  + border-top-style: hidden;  + border-bottom-style: hidden;  +}  +table.tableblock.frame-none {  + border-style: hidden;  +}  +  +th.tableblock.halign-left, td.tableblock.halign-left {  + text-align: left;  +}  +th.tableblock.halign-center, td.tableblock.halign-center {  + text-align: center;  +}  +th.tableblock.halign-right, td.tableblock.halign-right {  + text-align: right;  +}  +  +th.tableblock.valign-top, td.tableblock.valign-top {  + vertical-align: top;  +}  +th.tableblock.valign-middle, td.tableblock.valign-middle {  + vertical-align: middle;  +}  +th.tableblock.valign-bottom, td.tableblock.valign-bottom {  + vertical-align: bottom;  +}  +  +  +/*  + * manpage specific  + *  + * */  +  +body.manpage h1 {  + padding-top: 0.5em;  + padding-bottom: 0.5em;  + border-top: 2px solid silver;  + border-bottom: 2px solid silver;  +}  +body.manpage h2 {  + border-style: none;  +}  +body.manpage div.sectionbody {  + margin-left: 3em;  +}  +  +@media print {  + body.manpage div#toc { display: none; }  +}  +  +  +</style>  +<script type="text/javascript">  +/*<![CDATA[*/  +var asciidoc = { // Namespace.  +  +/////////////////////////////////////////////////////////////////////  +// Table Of Contents generator  +/////////////////////////////////////////////////////////////////////  +  +/* Author: Mihai Bazon, September 2002  + * http://students.infoiasi.ro/~mishoo  + *  + * Table Of Content generator  + * Version: 0.4  + *  + * Feel free to use this script under the terms of the GNU General Public  + * License, as long as you do not remove or alter this notice.  + */  +  + /* modified by Troy D. Hanson, September 2006. License: GPL */  + /* modified by Stuart Rackham, 2006, 2009. License: GPL */  +  +// toclevels = 1..4.  +toc: function (toclevels) {  +  + function getText(el) {  + var text = "";  + for (var i = el.firstChild; i != null; i = i.nextSibling) {  + if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.  + text += i.data;  + else if (i.firstChild != null)  + text += getText(i);  + }  + return text;  + }  +  + function TocEntry(el, text, toclevel) {  + this.element = el;  + this.text = text;  + this.toclevel = toclevel;  + }  +  + function tocEntries(el, toclevels) {  + var result = new Array;  + var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');  + // Function that scans the DOM tree for header elements (the DOM2  + // nodeIterator API would be a better technique but not supported by all  + // browsers).  + var iterate = function (el) {  + for (var i = el.firstChild; i != null; i = i.nextSibling) {  + if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {  + var mo = re.exec(i.tagName);  + if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {  + result[result.length] = new TocEntry(i, getText(i), mo[1]-1);  + }  + iterate(i);  + }  + }  + }  + iterate(el);  + return result;  + }  +  + var toc = document.getElementById("toc");  + if (!toc) {  + return;  + }  +  + // Delete existing TOC entries in case we're reloading the TOC.  + var tocEntriesToRemove = [];  + var i;  + for (i = 0; i < toc.childNodes.length; i++) {  + var entry = toc.childNodes[i];  + if (entry.nodeName.toLowerCase() == 'div'  + && entry.getAttribute("class")  + && entry.getAttribute("class").match(/^toclevel/))  + tocEntriesToRemove.push(entry);  + }  + for (i = 0; i < tocEntriesToRemove.length; i++) {  + toc.removeChild(tocEntriesToRemove[i]);  + }  +  + // Rebuild TOC entries.  + var entries = tocEntries(document.getElementById("content"), toclevels);  + for (var i = 0; i < entries.length; ++i) {  + var entry = entries[i];  + if (entry.element.id == "")  + entry.element.id = "_toc_" + i;  + var a = document.createElement("a");  + a.href = "#" + entry.element.id;  + a.appendChild(document.createTextNode(entry.text));  + var div = document.createElement("div");  + div.appendChild(a);  + div.className = "toclevel" + entry.toclevel;  + toc.appendChild(div);  + }  + if (entries.length == 0)  + toc.parentNode.removeChild(toc);  +},  +  +  +/////////////////////////////////////////////////////////////////////  +// Footnotes generator  +/////////////////////////////////////////////////////////////////////  +  +/* Based on footnote generation code from:  + * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html  + */  +  +footnotes: function () {  + // Delete existing footnote entries in case we're reloading the footnodes.  + var i;  + var noteholder = document.getElementById("footnotes");  + if (!noteholder) {  + return;  + }  + var entriesToRemove = [];  + for (i = 0; i < noteholder.childNodes.length; i++) {  + var entry = noteholder.childNodes[i];  + if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")  + entriesToRemove.push(entry);  + }  + for (i = 0; i < entriesToRemove.length; i++) {  + noteholder.removeChild(entriesToRemove[i]);  + }  +  + // Rebuild footnote entries.  + var cont = document.getElementById("content");  + var spans = cont.getElementsByTagName("span");  + var refs = {};  + var n = 0;  + for (i=0; i<spans.length; i++) {  + if (spans[i].className == "footnote") {  + n++;  + var note = spans[i].getAttribute("data-note");  + if (!note) {  + // Use [\s\S] in place of . so multi-line matches work.  + // Because JavaScript has no s (dotall) regex flag.  + note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];  + spans[i].innerHTML =  + "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +  + "' title='View footnote' class='footnote'>" + n + "</a>]";  + spans[i].setAttribute("data-note", note);  + }  + noteholder.innerHTML +=  + "<div class='footnote' id='_footnote_" + n + "'>" +  + "<a href='#_footnoteref_" + n + "' title='Return to text'>" +  + n + "</a>. " + note + "</div>";  + var id =spans[i].getAttribute("id");  + if (id != null) refs["#"+id] = n;  + }  + }  + if (n == 0)  + noteholder.parentNode.removeChild(noteholder);  + else {  + // Process footnoterefs.  + for (i=0; i<spans.length; i++) {  + if (spans[i].className == "footnoteref") {  + var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");  + href = href.match(/#.*/)[0]; // Because IE return full URL.  + n = refs[href];  + spans[i].innerHTML =  + "[<a href='#_footnote_" + n +  + "' title='View footnote' class='footnote'>" + n + "</a>]";  + }  + }  + }  +},  +  +install: function(toclevels) {  + var timerId;  +  + function reinstall() {  + asciidoc.footnotes();  + if (toclevels) {  + asciidoc.toc(toclevels);  + }  + }  +  + function reinstallAndRemoveTimer() {  + clearInterval(timerId);  + reinstall();  + }  +  + timerId = setInterval(reinstall, 500);  + if (document.addEventListener)  + document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);  + else  + window.onload = reinstallAndRemoveTimer;  +}  +  +}  +asciidoc.install();  +/*]]>*/  +</script>  +</head>  +<body class="article">  +<div id="header">  +<h1>How to integrate new subcommands</h1>  +</div>  +<div id="content">  +<div id="preamble">  +<div class="sectionbody">  +<div class="paragraph"><p>This is how-to documentation for people who want to add extension  +commands to git. It should be read alongside api-builtin.txt.</p></div>  +</div>  +</div>  +<div class="sect1">  +<h2 id="_runtime_environment">Runtime environment</h2>  +<div class="sectionbody">  +<div class="paragraph"><p>git subcommands are standalone executables that live in the git exec  +path, normally /usr/lib/git-core. The git executable itself is a  +thin wrapper that knows where the subcommands live, and runs them by  +passing command-line arguments to them.</p></div>  +<div class="paragraph"><p>(If "git foo" is not found in the git exec path, the wrapper  +will look in the rest of your $PATH for it. Thus, it&#8217;s possible  +to write local git extensions that don&#8217;t live in system space.)</p></div>  +</div>  +</div>  +<div class="sect1">  +<h2 id="_implementation_languages">Implementation languages</h2>  +<div class="sectionbody">  +<div class="paragraph"><p>Most subcommands are written in C or shell. A few are written in  +Perl.</p></div>  +<div class="paragraph"><p>While we strongly encourage coding in portable C for portability,  +these specific scripting languages are also acceptable. We won&#8217;t  +accept more without a very strong technical case, as we don&#8217;t want  +to broaden the git suite&#8217;s required dependencies. Import utilities,  +surgical tools, remote helpers and other code at the edges of the  +git suite are more lenient and we allow Python (and even Tcl/tk),  +but they should not be used for core functions.</p></div>  +<div class="paragraph"><p>This may change in the future. Especially Python is not allowed in  +core because we need better Python integration in the git Windows  +installer before we can be confident people in that environment  +won&#8217;t experience an unacceptably large loss of capability.</p></div>  +<div class="paragraph"><p>C commands are normally written as single modules, named after the  +command, that link a collection of functions called libgit. Thus,  +your command <em>git-foo</em> would normally be implemented as a single  +"git-foo.c" (or "builtin/foo.c" if it is to be linked to the main  +binary); this organization makes it easy for people reading the code  +to find things.</p></div>  +<div class="paragraph"><p>See the CodingGuidelines document for other guidance on what we consider  +good practice in C and shell, and api-builtin.txt for the support  +functions available to built-in commands written in C.</p></div>  +</div>  +</div>  +<div class="sect1">  +<h2 id="_what_every_extension_command_needs">What every extension command needs</h2>  +<div class="sectionbody">  +<div class="paragraph"><p>You must have a man page, written in asciidoc (this is what git help  +followed by your subcommand name will display). Be aware that there is  +a local asciidoc configuration and macros which you should use. It&#8217;s  +often helpful to start by cloning an existing page and replacing the  +text content.</p></div>  +<div class="paragraph"><p>You must have a test, written to report in TAP (Test Anything Protocol).  +Tests are executables (usually shell scripts) that live in the <em>t</em>  +subdirectory of the tree. Each test name begins with <em>t</em> and a sequence  +number that controls where in the test sequence it will be executed;  +conventionally the rest of the name stem is that of the command  +being tested.</p></div>  +<div class="paragraph"><p>Read the file t/README to learn more about the conventions to be used  +in writing tests, and the test support library.</p></div>  +</div>  +</div>  +<div class="sect1">  +<h2 id="_integrating_a_command">Integrating a command</h2>  +<div class="sectionbody">  +<div class="paragraph"><p>Here are the things you need to do when you want to merge a new  +subcommand into the git tree.</p></div>  +<div class="olist arabic"><ol class="arabic">  +<li>  +<p>  +Don&#8217;t forget to sign off your patch!  +</p>  +</li>  +<li>  +<p>  +Append your command name to one of the variables BUILTIN_OBJS,  +EXTRA_PROGRAMS, SCRIPT_SH, SCRIPT_PERL or SCRIPT_PYTHON.  +</p>  +</li>  +<li>  +<p>  +Drop its test in the t directory.  +</p>  +</li>  +<li>  +<p>  +If your command is implemented in an interpreted language with a  +p-code intermediate form, make sure .gitignore in the main directory  +includes a pattern entry that ignores such files. Python .pyc and  +.pyo files will already be covered.  +</p>  +</li>  +<li>  +<p>  +If your command has any dependency on a particular version of  +your language, document it in the INSTALL file.  +</p>  +</li>  +<li>  +<p>  +There is a file command-list.txt in the distribution main directory  +that categorizes commands by type, so they can be listed in appropriate  +subsections in the documentation&#8217;s summary command list. Add an entry  +for yours. To understand the categories, look at git-cmmands.txt  +in the main directory.  +</p>  +</li>  +<li>  +<p>  +Give the maintainer one paragraph to include in the RelNotes file  +to describe the new feature; a good place to do so is in the cover  +letter [PATCH 0/n].  +</p>  +</li>  +</ol></div>  +<div class="paragraph"><p>That&#8217;s all there is to it.</p></div>  +</div>  +</div>  +</div>  +<div id="footnotes"><hr /></div>  +<div id="footer">  +<div id="footer-text">  +Last updated 2012-12-21 15:44:56 PST  +</div>  +</div>  +</body>  +</html>